home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1999 March / EnigmA AMIGA RUN 35 (1999)(G.R. Edizioni)(IT)[!][issue 1999-03].iso / earcd / devel / vbcc-68k-src / machines / amiga / doc / vclib68k.doc < prev   
Text File  |  1999-01-01  |  8KB  |  282 lines
  1. vc.lib - C library for the Amiga68k version of vbcc
  2.  
  3.  
  4. INTRODUCTION
  5.  
  6.     vc.lib is a (rather) ANSI compliant C library for use with the
  7.     Amiga68k version of vbcc.
  8.  
  9.     It is written largely in C and some parts are not Amiga specific.
  10.  
  11.     You can also create a small data library (this one will probably
  12.     be in the archive already as vcs.lib), a small-code-version, a
  13.     020-version etc. or combinations of this (see COMPILING).
  14.  
  15.     Note that you have to link with a math library if you want to use
  16.     floating point. All math functions, special startup code and
  17.     printf/scanf functions which support floating point are contained in
  18.     the math libraries only.
  19.     At the moment there are four math libraries:
  20.  
  21.         mieee.lib   This one uses the C= math libraries. The startup code
  22.                     will always open MathIeeeSingBas.library,
  23.                     MathIeeeDoubBas.library and MathIeeeDoubTrans.library.
  24.                     Float return values are passed in d0, double return
  25.                     values are passed in d0/d1.
  26.                     A 68000 is sufficient to use this library.
  27.                     You must not specify -fpu=... when you use this library.
  28.  
  29.         m881.lib    This one uses direct FPU instructions and function
  30.                     return values are passed in fp0. You must have a
  31.                     68020 or higher and an FPU to use this library. You
  32.                     also have to specify -fpu=68881.
  33.                     Several FPU instructions that have to be emulated on
  34.                     040/060 may be used.
  35.  
  36.         m040.lib    This one uses only direct FPU instructions that do not
  37.                     have to be emulated on a 040/060. Other functions use
  38.                     the Motorola emulation routines modified by
  39.                     Aki M Laukkanen.
  40.                     It should be used for programs compiled for 040 or 060
  41.                     with FPU and replaces the former m040.lib which is now
  42.                     called m040o.lib.
  43.                     Return values are passed in fp0.
  44.  
  45.  
  46.     To link with one of those libraries add e.g. the -lmieee option to vc or
  47.     specify mieee.lib before vc.lib if you do the linking by hand.
  48.  
  49.     Some info about amiga.lib can be found in fd2lib.doc.
  50.  
  51.  
  52. LEGAL
  53.  
  54.     vc.lib is public domain. Certain parts have been taken from other
  55.     PD libraries (mainly libnix).
  56.     The same applies to m881.lib, m040.lib and mieee.lib.
  57.  
  58.  
  59. STARTUP etc.
  60.  
  61.     The startup code currently consists of a slightly modified standard
  62.     Amiga startup and the file _main.c. The startup code sets up some
  63.     global variables and initializes stdin, stdout and stderr.
  64.     The exit code closes all open files and frees all memory.
  65.     If you link with a math library the startup/exit code will be taken
  66.     from there if necessary.
  67.  
  68.  
  69. INLINING
  70.  
  71.     Several header-files provide support for inlining of certain library
  72.     functions. If the preprocessor-symbol __INLINE_<function> is defined
  73.     the corresponding function may be inlined. E.g if you compile with
  74.  
  75.         vc -O3 -D__INLINE_STRCPY
  76.  
  77.     then calls to strcpy() will be inlined. Note however that the symbol
  78.     must be defined at the time string.h is included and, of course, that
  79.     function inlining must be turned on.
  80.  
  81.     Not all library functions are prepared for inlining but only those
  82.     that are reasonably small, are not implemented as macros and can
  83.     safely be inlined. E.g. __INLINE_QSORT will be ignored.
  84.  
  85.     The symbol __INLINE_ALL will cause inlining of all functions which
  86.     can be inlined.
  87.  
  88.     You must have the source to the library functions in the appropriate
  89.     directories, e.g. strcpy must be reachable via
  90.  
  91.         #include "vbccm68k:libsrc/string/strcpy.c"
  92.  
  93.     (This could be a problem when cross-compiling.)
  94.  
  95.  
  96. STDIO
  97.  
  98.     The following functions are implemented at the moment:
  99.  
  100.     fopen()     binary and text modes are the same
  101.     fclose()
  102.     fflush()
  103.     fgetc()
  104.     ungetc()
  105.     fputc()
  106.     fgets()
  107.     fputs()
  108.     fread()
  109.     fwrite()
  110.     gets()      never use it...
  111.     puts()
  112.     ftell()
  113.     fseek()
  114.     remove()
  115.     rename()
  116.     rewind()
  117.     setvbuf()
  118.     setbuf()
  119.     feof()
  120.     ferror()
  121.     prerror()
  122.     tmpnam()
  123.     tmpfile()   always returns an error at the moment
  124.     fgetpos()
  125.     fsetpos()
  126.     printf()    taken from libnix; link with a math library if you need fp
  127.     fprintf()     "
  128.     sprintf()     "
  129.     vprintf()     "
  130.     vfprintf()    "
  131.     vsprintf()    "
  132.     scanf()       "
  133.     fscanf()      "
  134.     sscanf()      "
  135.  
  136.     There are macros for a few functions. Some of them will cause a
  137.     warning 129. This is necessary to make them fully conforming. You can
  138.     safely ignore those warnings or use -dontwarn=129.
  139.  
  140.  
  141. STDLIB
  142.  
  143.     The following functions do exist.
  144.  
  145.     malloc()
  146.     free()
  147.     calloc()
  148.     realloc()
  149.     rand()      taken from libnix
  150.     srand()       "
  151.     system()    uses SystemTagList or Execute depending on OS version
  152.     abs()
  153.     labs()
  154.     div()
  155.     ldiv()
  156.     abort()
  157.     atexit()
  158.     getenv()    taken from libnix
  159.     qsort()       "
  160.     bsearch()     "
  161.     strtol()      "
  162.     strtoul()     "
  163.     atol()        "
  164.     atoi()        "
  165.     atof()      taken from libnix; link with a math library to use this
  166.     strtod()      "
  167.  
  168.  
  169. TIME
  170.  
  171.     The standard functions should exist. Taken from libnix.
  172.     clock() always returns -1.
  173.     Link with a math library if you use difftime().
  174.  
  175.  
  176. STRING
  177.  
  178.     The standard functions should exist.
  179.  
  180.  
  181. CTYPE
  182.  
  183.     The standard functions should exist.
  184.  
  185.  
  186. LIMITS
  187.  
  188.     No functions.
  189.  
  190.  
  191. FLOAT
  192.  
  193.     I do not know what has to be there, yet, but the most important things
  194.     should be there (and approximately correct). No functions.
  195.  
  196.  
  197. MATH
  198.  
  199.     You have to link with a math library to use these functions.
  200.     The following functions should be there, but they may be not precise
  201.     enough or otherwise not fully ANSI conform in some cases (e.g. errno
  202.     is not set and pow() with m881 is probably not fully conforming):
  203.  
  204.     sin(), cos(), tan()
  205.     sinh(), cosh(), tanh()
  206.     asin(), acos(), atan(), atan2()
  207.     exp(), log(), log10(), pow()
  208.     ceil(), floor()
  209.     sqrt()
  210.     fabs()
  211.     fmod()
  212.     ldexp(). frexp()
  213.  
  214.     If _M68881, _M68040 or _M68060 is #defined when math.h is included
  215.     inline assembly will be generated for certain functions.
  216.  
  217.  
  218. STDDEF
  219.  
  220.     Currently defines size_t, fpos_t, ptrdiff_t, wchar_t, time_t, clock_t,
  221.     NULL and offsetof. No functions.
  222.  
  223.  
  224. STDARG
  225.  
  226.     Defines va_list, va_start, va_arg and va_end. Seems to work well, but
  227.     vbcc gives an 'offset equals size of object' warning. No functions.
  228.  
  229.  
  230. ASSERT
  231.  
  232.     Not really tested yet. No functions.
  233.  
  234.  
  235. ERRNO
  236.  
  237.     The include file and errno is there, but most functions do not set
  238.     errno. No functions.
  239.  
  240.  
  241. SETJMP
  242.  
  243.     Oh well...I only wrote down some lines, but never tested it.
  244.     Also I think maybe there should be a special version for fpu, but it
  245.     is not required by the ANSI standard AFAIK.
  246.  
  247.  
  248. SIGNAL
  249.  
  250.     signal() and raise() are there, but always return an error.
  251.  
  252.  
  253. LOCALE
  254.  
  255.     localeconv() and setlocale() are there, but setlocale() does not do
  256.     anything.
  257.  
  258.  
  259. Again, there may be some errors or missing things in the include files
  260. and the library.
  261.  
  262.  
  263. COMPILING
  264.  
  265.     If you want to compile the libraries yourself you should be able
  266.     to call the Make#?.script scripts from their directory and the rest
  267.     should be done automatically and the resulting .lib file will be
  268.     copied to vlib: (so take care you do not overwrite another library).
  269.     If you want to create special libraries (e.g. a vc.lib for 020+)
  270.     you have to edit the Make scripts.
  271.     E.g. to create the small-data-vcs.lib change add -sd in the
  272.     alias cc ... line and replace every following vc by vcs.
  273.  
  274.     Currently there is no small-data-version of the math libraries (it
  275.     should not make a difference with m881.lib, but with mieee.lib and
  276.     m040.lib).
  277.  
  278.  
  279.  
  280. Volker                                              volker@vb.franken.de
  281.  
  282.